---
title: IAM Credentials
description: Configure the IAM credentials that's used to deploy your app.
---

SST deploys your AWS resources using your AWS credentials. In this guide we'll look at how to set these credentials, the basic set of permissions it needs, and how to customize it.

---

## Credentials

There are a couple of different ways to set the credentials that your app will use. The simplest is using a credentials file.

However, if you're still figuring out how to configure your AWS account, we recommend [following our guide on it](/docs/aws-accounts).

---

#### From a file

By default, your AWS credentials are in a file:

- `~/.aws/credentials` on Linux, Unix, macOS
- `C:\Users\USER_NAME\.aws\credentials` on Windows

If the credentials file does not exist on your machine.

1. Follow this to [create an IAM user](https://sst.dev/chapters/create-an-iam-user.html)
2. And then use this to [configure the credentials](https://sst.dev/chapters/configure-the-aws-cli.html)

Below we'll look at how to customize the permissions that are granted to this user.

---

Your credentials file might look like:

```bash title="~/.aws/credentials"
[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
```

Where `default` is the name of the credentials profile.

And if you have multiple credentials, it might look like:

```bash title="~/.aws/credentials"
[default]
aws_access_key_id = <DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <DEFAULT_SECRET_ACCESS_KEY>

[staging]
aws_access_key_id = <STAGING_ACCESS_KEY_ID>
aws_secret_access_key = <STAGING_SECRET_ACCESS_KEY>

[production]
aws_access_key_id = <PRODUCTION_ACCESS_KEY_ID>
aws_secret_access_key = <PRODUCTION_SECRET_ACCESS_KEY>
```

By default, SST uses the credentials for the `default` profile. To use one of the other profiles, set the `profile` in your `sst.config.ts`.

```ts title="sst.config.ts"
{
  providers: {
    aws: {
      profile: "staging"
    }
  }
}
```

You can customize this for the stage your app is being deployed to.

```ts title="sst.config.ts"
app(input) {
  return {
    // ...
    providers: {
      aws: {
        profile: input?.stage === "staging" ? "staging" : "default"
      }
    }
  };
},
```

If you've configured AWS credentials previously through the `AWS_PROFILE` environment variable or through a `.env` file, it will override the profile set in your `sst.config.ts`. So make sure to remove any references to `AWS_PROFILE`.

---

#### From environment variables

SST can also detect AWS credentials in your environment and use them to deploy.

- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`

If you are using temporary credentials, you can also set the `AWS_SESSION_TOKEN`.

This is useful when you are deploying through a CI environment and there are no credential files around.

---

### Precedence

If you have AWS credentials set in multiple places, SST will first look at:

1. Environment variables

   This includes `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or `AWS_SESSION_TOKEN`, and `AWS_PROFILE`. This also includes environment variables set in a `.env` file.

2. SST config

   Then it'll check for the credentials or `profile` in your `sst.config.ts`.

3. AWS config

   It'll then check for the `[default]` profile in your `~/.aws/config` or `C:\Users\USER_NAME\.aws\config`.

4. Credential files

   Finally, it'll look for any static credentials in your `~/.aws/credentials` or `C:\Users\USER_NAME\.aws\credentials`.

---

## IAM permissions

The credentials above are for an IAM user and it comes with an IAM policy. This defines what resources the given user has access to. By default, we are using `AdministratorAccess`. This gives your user complete access.

However, if you are using SST at your company, you want to secure these permissions. Here we'll look at exactly what SST needs and how you can go about customizing it.

---

Let's start with an IAM policy you can _copy and paste_.

<details>
<summary>**Copy IAM Policy**</summary>

```json title="iam-policy.json"
{
    "Version": "2012-10-17",
    "Statement": [
      {
          "Sid": "ManageBootstrapStateBucket",
          "Effect": "Allow",
          "Action": [
              "s3:CreateBucket",
              "s3:PutBucketVersioning",
              "s3:PutBucketNotification",
              "s3:PutBucketPolicy",
              "s3:DeleteObject",
              "s3:GetObject",
              "s3:ListBucket",
              "s3:PutObject"
          ],
          "Resource": [
              "arn:aws:s3:::sst-state-*"
          ]
      },
      {
          "Sid": "ManageBootstrapAssetBucket",
          "Effect": "Allow",
          "Action": [
              "s3:CreateBucket",
              "s3:PutBucketVersioning",
              "s3:PutBucketNotification",
              "s3:PutBucketPolicy",
              "s3:DeleteObject",
              "s3:GetObject",
              "s3:ListBucket",
              "s3:PutObject"
          ],
          "Resource": [
              "arn:aws:s3:::sst-asset-*"
          ]
      },
      {
          "Sid": "ManageBootstrapECRRepo",
          "Effect": "Allow",
          "Action": [
              "ecr:CreateRepository",
              "ecr:DescribeRepositories"
          ],
          "Resource": [
              "arn:aws:ecr:REGION:ACCOUNT:repository/sst-asset"
          ]
      },
      {
          "Sid": "ManageBootstrapSSMParameter",
          "Effect": "Allow",
          "Action": [
              "ssm:GetParameters",
              "ssm:PutParameter"
          ],
          "Resource": [
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/passphrase/*",
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/bootstrap"
          ]
      },
      {
          "Sid": "Deployments",
          "Effect": "Allow",
          "Action": [
              "*"
          ],
          "Resource": [
              "*"
          ]
      },
      {
          "Sid": "ManageSecrets",
          "Effect": "Allow",
          "Action": [
              "ssm:DeleteParameter",
              "ssm:GetParameter",
              "ssm:GetParameters",
              "ssm:GetParametersByPath",
              "ssm:PutParameter"
          ],
          "Resource": [
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/*"
          ]
      },
      {
          "Sid": "LiveLambdaSocketConnection",
          "Effect": "Allow",
          "Action": [
              "appsync:EventSubscribe",
              "appsync:EventPublish",
              "appsync:EventConnect"
          ],
          "Resource": [
              "*"
          ]
      }
    ]
}
```

</details>

This list roughly breaks down into the following:

1. Permissions needed to bootstrap SST in your AWS account
2. Permissions needed to deploy your app
3. Permissions needed by the CLI

Let's look at them in detail.

---

### Bootstrap

SST needs to [bootstrap](/docs/state/#bootstrap) each AWS account, in each region, once. This happens automatically when you run `sst deploy` or `sst dev`.

There are a couple of different things being bootstrapped and these are the permissions they need:

- Permissions to create the bootstrap bucket for storing state.

  ```json
  {
    "Sid": "ManageBootstrapStateBucket",
    "Effect": "Allow",
    "Action": [
      "s3:CreateBucket",
      "s3:PutBucketVersioning",
      "s3:PutBucketNotification",
      "s3:DeleteObject",
      "s3:GetObject",
      "s3:ListBucket",
      "s3:PutObject"
    ],
    "Resource": [
      "arn:aws:s3:::sst-state-*"
    ]
  }
  ```

- Permissions to create the bootstrap bucket for storing the assets in your app. These include the Lambda function bundles and static assets in your frontends.

  ```json
  {
    "Sid": "ManageBootstrapAssetBucket",
    "Effect": "Allow",
    "Action": [
      "s3:CreateBucket",
      "s3:PutBucketVersioning",
      "s3:DeleteObject",
      "s3:GetObject",
      "s3:ListBucket",
      "s3:PutObject"
    ],
    "Resource": [
      "arn:aws:s3:::sst-asset-*"
    ]
  }
  ```

- Permissions to create the bootstrap ECR repository for hosting the Docker images in your app.

  ```json
  {
      "Sid": "ManageBootstrapECRRepo",
      "Effect": "Allow",
      "Action": [
        "ecr:CreateRepository",
        "ecr:DescribeRepositories"
      ],
      "Resource": [
        "arn:aws:ecr:REGION:ACCOUNT:repository/sst-asset"
      ]
  }
  ```

- Permissions to create the bootstrap SSM parameter. This parameter stores information about the deployed bootstrap resources.

  ```json
  {
    "Sid": "ManageBootstrapSSMParameter",
    "Effect": "Allow",
    "Action": [
      "ssm:GetParameters",
      "ssm:PutParameter"
    ],
    "Resource": [
      "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/passphrase/*",
      "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/bootstrap"
    ]
  }
  ```

---

### Deploy

The permissions that SST needs to deploy the resources in your app, depends on what you have in your app.

The following block is placed as a template in the IAM policy above for you to customize.

```json
{
  "Sid": "Deployments",
  "Effect": "Allow",
  "Action": [
    "*"
  ],
  "Resource": [
    "*"
  ]
}
```

Below we'll look at how you can try customizing this.

---

### CLI

The SST CLI also makes some AWS SDK calls to your account. Here are the IAM permissions it needs.

- Permissions to manage your [secrets](/docs/component/secret).

  ```json
  {
    "Sid": "ManageSecrets",
    "Effect": "Allow",
    "Action": [
      "ssm:DeleteParameter",
      "ssm:GetParameter",
      "ssm:GetParameters",
      "ssm:GetParametersByPath",
      "ssm:PutParameter"
    ],
    "Resource": [
      "arn:aws:ssm:us-east-1:112233445566:parameter/sst/*"
    ]
  }
  ```

- And permissions to connect to the IoT endpoint in `sst dev` to run your functions [_Live_](/docs/live).

  ```json
  {
    "Sid": "LiveLambdaSocketConnection",
    "Effect": "Allow",
    "Action": [
      "iot:DescribeEndpoint",
      "iot:Connect",
      "iot:Subscribe",
      "iot:Publish",
      "iot:Receive"
    ],
    "Resource": [
      "*"
    ]
  }
  ```

---

## Minimize permissions

Editing the above policy based on the resources you are adding to your app can be tedious. Here's an approach to consider.

- Sandbox accounts

  Start by creating separate AWS accounts for your teammates for their dev usage. In these sandbox accounts, you can grant `AdministratorAccess`. This avoids having to modify their permissions every time they make some changes.

- IAM Access Analyzer

  For your staging accounts, you can start by granting a broad permissions policy. Then after deploying your app and allowing it to run for a period of time. You can use your CloudTrail events to identify the actions and services used by that IAM user. The [IAM Access Analyzer](https://aws.amazon.com/iam/access-analyzer/) can then generate an IAM policy based on this activity, which you can use to replace the original policy.

  You can now use this for your production accounts. Learn more about how to use the [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-generation.html).

In general, you want to make sure you audit the IAM permissions you are granting on a regular basis.
